Added a section on how to compute pixel offsets for

2004-01-06  Federico Mena Quintero  <federico@ximian.com>

* gdk-pixbuf/tmpl/gdk-pixbuf.sgml: Added a section on how to
compute pixel offsets for gdk_pixbuf_get_pixels().

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index f077eda35d78a54dd66296bd76a11969f06480d3..0834d38e83d16d3c44e078d0ad5af31681d08159 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -15,6 +15,11 @@ Wed Jan  7 01:26:07 2004  Matthias Clasen  <maclas@gmx.de>
 
        * gdk-pixbuf/gdk-pixbuf-sections.txt: Add gdk_pixbuf_get_file_info.
 
+2004-01-06  Federico Mena Quintero  <federico@ximian.com>
+
+       * gdk-pixbuf/tmpl/gdk-pixbuf.sgml: Added a section on how to
+       compute pixel offsets for gdk_pixbuf_get_pixels().
+
 Mon Dec 29 01:40:20 2003  Matthias Clasen  <maclas@gmx.de>
 
        * gtk/gtk-sections.txt: Add gtk_accel_map_{un,}lock_path.

diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml
index 728ae31d1b8729a601d79acae5619aaffbe1ecd0..7cbef5a28dc71e934548f02d7adbcd3481300ac0 100644 (file)
--- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml
@@ -11,6 +11,81 @@ Information that describes an image.
     information that describes an image in memory.
   </para>
 
+  <section id="image-data">
+    <title>Image Data</title>
+
+    <para>
+      Image data in a pixbuf is stored in memory in uncompressed,
+      packed format.  Rows in the image are stored top to bottom, and
+      in each row pixels are stored from left to right.  There may be
+      padding at the end of a row.  The "rowstride" value of a pixbuf,
+      as returned by gdk_pixbuf_get_rowstride(), indicates the number
+      of bytes between rows.
+    </para>
+
+    <example id="put-pixel">
+      <title>put_pixel() example</title>
+
+      <para>
+       The following code illustrates a simple put_pixel() function
+       for RGB pixbufs with 8 bits per channel with an alpha channel.
+       It is not included in the gdk-pixbuf library for performance
+       reasons; rather than making several function calls for each
+       pixel, your own code can take shortcuts.
+      </para>
+
+      <programlisting>
+static void
+put_pixel (GdkPixbuf *pixbuf, int x, int y, guchar red, guchar green, guchar blue, guchar alpha)
+{
+  int width, height, rowstride, n_channels;
+  guchar *pixels, *p;
+
+  n_channels = gdk_pixbuf_get_n_channels (pixbuf);
+
+  g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB);
+  g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8);
+  g_assert (gdk_pixbuf_get_has_alpha (pixbuf));
+  g_assert (n_channels == 4);
+
+  width = gdk_pixbuf_get_width (pixbuf);
+  height = gdk_pixbuf_get_height (pixbuf);
+
+  g_assert (x &gt;= 0 && x < width);
+  g_assert (y &gt;= 0 && y < height);
+
+  rowstride = gdk_pixbuf_get_rowstride (pixbuf);
+  pixels = gdk_pixbuf_get_pixels (pixbuf);
+
+  p = pixels + y * rowstride + x * n_channels;
+  p[0] = red;
+  p[1] = green;
+  p[2] = blue;
+  p[3] = alpha;
+}
+      </programlisting>
+
+      <para>
+       This function will not work for pixbufs with images that are
+       other than 8 bits per sample or channel, but it will work for
+       most of the pixbufs that GTK+ uses.
+      </para>
+    </example>
+
+    <note>
+      <para>
+       If you are doing memcpy() of raw pixbuf data, note that the
+       last row in the pixbuf may not be as wide as the full
+       rowstride, but rather just as wide as the pixel data needs to
+       be.  That is, it is unsafe to do <literal>memcpy (dest,
+       pixels, rowstride * height)</literal> to copy a whole pixbuf.
+       Use gdk_pixbuf_copy() instead, or compute the width in bytes
+       of the last row as <literal>width * ((n_channels *
+       bits_per_sample + 7) / 8)</literal>.
+      </para>
+    </note>
+  </section>
+
 <!-- ##### SECTION See_Also ##### -->
   <para>
   </para>
@@ -76,6 +151,46 @@ In the future it will do full alpha compositing.
   </para>
 
 
+<!-- ##### ARG GdkPixbuf:bits-per-sample ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GdkPixbuf:colorspace ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GdkPixbuf:has-alpha ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GdkPixbuf:height ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GdkPixbuf:n-channels ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GdkPixbuf:pixels ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GdkPixbuf:rowstride ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GdkPixbuf:width ##### -->
+<para>
+
+</para>
+
 <!-- ##### FUNCTION gdk_pixbuf_get_colorspace ##### -->
 <para>
 
@@ -163,3 +278,9 @@ End:
 @Returns: 
 
 
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2")
+End:
+-->